Skip to main content

Migrating from Next.js to Catalyst

Step 1: Project Setup​

Create a new Catalyst project:

npx [email protected]

Perform the entire migration in a new folder to avoid dependency conflicts between Next.js and Catalyst.

Step 2: Project Structure​

  1. Understand the differences in project structure:

    1. Next.js:
          pages/
          public/
          styles/
    2. Catalyst:
          config/  # Configuration keys
          src/     # Application source code
          components/
          routes/
          services/
          utils/
          client/  # Client app entry point
          server/  # API and middleware
          build/   # Bundled code

  2. Move your existing components from various locations to src/components/.

  3. Relocate any utility functions to src/utils/.

Step 3: Routing​

  1. Replace Next.js file-based routing with Catalyst's route configuration.

  2. Open src/routes/index.ts.

  3. Define your routes using the react-router-v6 style:

    const routes = [
    {
        path: "/",
        index: true,
        component: HomePage,
    },
    {
        path: "/cart",
        component: CartComponent,
        children: [
        {
            path: "",
            component: CartChild
        },
        {
            path: "prescription",
            component: Prescription
        }
        ],
    },
    {
        path: "/health-products",
        component: HealthProducts,
    },
    ]

  4. Update any dynamic routes to use react-router-v6 syntax.

Step 4: Pages and Components​

  1. Move your page components from pages/ to act as route components in the routes definition.

  2. Ensure all other components are in src/components/.

Step 5: Data Fetching​

  1. Replace Next.js data fetching methods (getServerSideProps, getStaticProps) with Catalyst's data fetching methods:

    const HomePage = () => <div>HomePage</div>

    HomePage.clientFetcher = (routerProps, fetcherArgs) => { return new Promise() }
    HomePage.serverFetcher = (serverRouterProps, fetcherArgs) => { return new Promise() }

  2. Update components to use the useCurrentRouteData hook where necessary. This hook provides:

    { isFetching, isFetched, error, data, refetch, clear }

Step 6: API Routes​

  1. Move your API routes from pages/api/ to the server/ directory in Catalyst.

  2. Update middleware:

    1. In Next.js, you used middleware.ts (or .js) in the project root.

    2. In Catalyst, create a function named addMiddlewares that receives the app server instance.

Step 7: State Management​

  1. Next.js typically uses external libraries like Redux or React Context.

  2. Catalyst provides built-in support for Redux and Redux Toolkit:

    1. Set up the Redux store in src/js/store/index.js.

    2. Update components to use Catalyst's built-in Redux support.

  3. If using other state management solutions:

    1. Implement at the root of your Catalyst application.

    2. Update components accordingly.

Step 8: Styling​

  1. Next.js has built-in CSS support and CSS Modules.

  2. Catalyst supports CSS Modules similarly:

    1. Update import statements in your components if necessary.

    2. Ensure all styling files are properly located in your new project structure.

Step 9: Image Handling​

  1. Replace next/image usage with standard <img> tags or create a custom image component.

  2. Update image paths to reflect the new project structure.

Step 10: Font Optimization​

  1. Remove next/font usage.

  2. Implement manual font optimization or integrate a third-party library for font management.

Step 11 :Script Management​

  1. Remove next/script usage.

  2. Implement manual script management or integrate React Helmet for script handling.

Step 12 :Layouts​

  1. Replace Next.js _app.js global layout with a Catalyst layout component.

  2. Integrate this layout component into your route definitions.

Step 13: Metadata and Head Management​

  1. Replace next/head usage with Catalyst's Head component:

    ```javascript
    import { Head, Body } from "catalyst"
    ```

    2.Update all components that were using next/head to use the new Head component.

Step 14: Environment Variables​

  1. Move environment variables from Next.js process.env to Catalyst's config/config.json.

  2. Separate client-side and server-side config.

  3. List client-side variables in ```CLIENT_ENV_KEYS.

Step 15: TypeScript​

Typescript is supported in version 0.0.1-canary.0

  1. Next.js has built-in TypeScript support.

  1. Catalyst is built with TypeScript:

    1. Ensure all your files use .ts or .tsx extensions.

    2. Update any TypeScript configurations to align with Catalyst's setup.

Step 16: Build and Deployment​

  1. Update your build script from next build to Catalyst's build process: npm run build.

  2. Modify your deployment scripts and configurations to work with the new Catalyst build output.

Step 17: Final Checks​

  1. Update all import statements to reflect the new project structure.

  2. Replace any remaining Next.js specific components or functions with their Catalyst equivalents or standard React/HTML alternatives.

  3. Test your application thoroughly to ensure all features work as expected in the new Catalyst environment.

Resources​